
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==

namespace Swaf
{
	public enum AppHandlerButton {OkButton};

	/// <summary>
	/// Implemented by client hosting environments to expose basic GUI functionality to the
	/// framework and its extensions.
	/// </summary>
	/// <remarks>
	/// Each type of hosting environment, such as Internet Explorer, a .NET Windows Forms application, or 
	/// Outlook, would have its own implementation of this interface to expose GUI features like displaying
	/// a basic message box, error message, and updating a "status message" (like that displayed in a status bar).
	/// </remarks>
	public interface IAppHandler
	{
		/// <summary>
		/// Set by framework components to represent the current application name, which is usually displayed
		/// in the "title bar" of the GUI client.
		/// </summary>
		/// <remarks>
		/// This value typically comes from the application configuration file being used by the client hosting
		/// environment.</remarks>
		string appName {get;set;}

		/// <summary>
		/// Set by framework components to represent the current window view the user of the client is viewing.
		/// </summary>
		/// <remarks>
		/// Typically, users work with GUI views of the application.  This property represents the name of the
		/// current view, which will change as the user "navigates" around the application (navigation being used
		/// generally and could be simple menu and toolbar selections).</remarks>
		string viewName {get;set;}

		/// <summary>
		/// Called by framework components as exceptions occur that are not fully handled by the application.
		/// </summary>
		/// <remarks>
		/// Usually a specialized message box will be displayed when this method is called, but implementors
		/// are free to do other things.</remarks>
		/// <param name="title">The title of the exception message.  This will typically be displayed in the
		/// title bar of a popup window.</param>
		/// <param name="msg">The user targeted message explaining the exception that occured.  This will typically be
		/// displayed in body of the popup window and can contain HTML formatting.</param>
		/// <param name="errorDetailsXML">The specific exception information that occured as an XML string
		/// of information.  Implementation are free to never actually display this to a user.</param>
		/// <param name="buttons"></param>
		void displayError(string title, string msg, string errorDetailsXML, AppHandlerButton buttons);

		/// <summary>
		/// Called by framework components to update the current status message, which is usually being displayed
		/// in the standard status bar.
		/// </summary>
		/// <param name="msg">The plain text to display in the status bar.  This should <b>not</b> contain
		/// HTML formatting.</param>
		void statusMessage(string msg);

		/// <summary>
		/// Called by framework components to display message to the user, which would typically be done
		/// via a popup message box window.</summary>
		/// <param name="title">Short plain text to display as the title of the message.  This should not
		/// contain HTML formatting.</param>
		/// <param name="msg">The text to display to the user as the main message.  This can contain
		/// HTML formatting.</param>
		void messageBox(string title, string msg);

		/// <summary>
		/// Called by framework components when the user triggers a "navigation" to another view.  The
		/// client hosting application would change the current view to the view specified.
		/// </summary>
		/// <remarks>
		/// Each client hosting environment is free to implement "navigation" in a wide variety of ways.
		/// Even a simple Internet Explorer hosting envirnment needs this in order to make the distinction
		/// between a real browser navigation to the new view, or a DHTML update of the current page to
		/// the new view.
		/// </remarks>
		/// <param name="viewName">The framework view name to navigate to.  This name should match a know view
		/// definition in the framework or a UnknownViewException will be thrown.</param>
		void navigateToView(string viewName);
	}
}
